<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Language" content="en-ca" />
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="description" content="Tasks" />
        <link rel="stylesheet" type="text/css" href="../style.css" />
        <title>Tasks</title>
    </head>
    <body>
        <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
            <tr>
                <td class="NavBar-Cell">
                    <a title="NAnt home page" href="http://nant.sourceforge.net"><b>NAnt</b></a>
                    <img src="../images/arrow.gif" alt="-&gt;" width="13" height="9" />
                    <a href="../index.html">Help</a>
                    <img alt="-&gt;" src="../images/arrow.gif" />
                    <a href="index.html">Fundamentals</a>
                    <img height="9" alt="-&gt;" src="../images/arrow.gif" width="13" />
                    Tasks
                </td>
                <td class="NavBar-Cell" align="right">
                    v0.91-alpha2
                </td>
            </tr>
        </table>
        <h1>Tasks</h1>
        <p class="topicstatus">[This is preliminary documentation and subject to change.]</p>
        <h2><a id="contents" />Contents</h2>
        <div>
            1 <a href="#introduction">Introduction</a><br />
            2 <a href="#taskloader">Loading custom extensions</a><br />
            <div style="margin-left: 20px;">
                2.1 <a href="#taskloader-automatic">Automatic discovery</a><br/>
                <div style="margin-left: 20px;">
                    2.1.1 <a href="#automatic-os">Operating system</a><br/>
                    2.1.2 <a href="#automatic-runtime">Runtime framework</a><br/>
                    2.1.3 <a href="#automatic-project">Project</a><br/>
                </div>
                2.2 <a href="#taskloader-forced">Forced scan</a><br/>
            </div>
        </div>
        <h2><a id="introduction" />1 Introduction</h2>
        <p>A task is a piece of code that can be executed.</p>
        <p>A task can have multiple attributes (or arguments, if you prefer).&nbsp; The 
            value of an attribute may contain references to a <a href="properties.html">property</a>.&nbsp; 
            These references will be resolved before the task is executed.</p>
        <p>Tasks have a common structure:</p>
        <blockquote><pre>&lt;<i>name</i> <i>attribute1</i>="<i>value1</i>" <i>attribute2</i>="<i>value2</i>" ... /&gt;</pre>
        </blockquote>
        <p>where <i>name</i> is the name of the task, <i>attribute#</i> is the attribute 
            name, and <i>value#</i> is the value for this attribute.</p>
        <p><img height="9" alt=">" src="../images/bullet.gif" width="5" />&nbsp;For 
            more information see the <a href="../tasks/index.html">Task Reference</a>.</p>
        <h2><a id="taskloader" />2 Loading custom extensions</h2>
        <p>
            Extensions can be devided in the following categories:
        </p>
        <ul>
            <li>Tasks</li>
            <li>Filters</li>
            <li>Functions</li>
            <li>Global Types</li>
        </ul>
        <p>
            NAnt currently provides two mechanisms to make third-party extensions available for use in build scripts:
        </p>
        <ul>
            <li>
                Automatic discovery
            </li>
            <li>
                Forced scan
            </li>
        </ul>
        <p>
            Both mechanisms use .NET reflection to scan one or more assemblies for the presence of extensions. When found,
            these extensions are registered in the NAnt type system, and from then on these are available for all build 
            scripts (in the current NAnt instance).
        </p>
        <h3><a id="taskloader-automatic" />2.1 Automatic discovery</h3>
        <p>
            To facilitate registration of extensions that are used in multiple (or even all) build 
            scripts, NAnt supports automatic discovery of extensions.
        </p>
        <p>
            In this context, automatic discovery means scanning a predefined set of directories and files for extensions.
        </p>
        <p>
            The actual set of directories and files that is scanned is determined by:
        </p>
        <ul>
            <li>Operating system</li>
            <li>Runtime framework</li>
            <li>Project</li>
        </ul>
        <h4><a id="automatic-os" />2.1.1 Operating system</h4>
        <p>
            When starting NAnt, all assemblies matching the following patterns will be scanned for extensions:
        </p>
        <div style="margin-left: 20px;">
            <p>
            <b>Windows</b>
            </p>
            <div style="margin-left: 20px;">
                <table style="width: 800px;" cellspacing="1" cellpadding="4">
                    <colgroup>
                        <col style="text-align: center;" />
                        <col style="text-align: center;" />
                        <col style="text-align: left;" />
                    </colgroup>
                    <tr>
                        <th>Pattern</th>
                        <th>Action</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td colspan="3"><hr /></td>
                    </tr>
                    <tr>
                        <td>*Tasks.dll</td>
                        <td>include</td>
                        <td>NAnt Core assemblies</td>
                    </tr>
                    <tr>
                        <td>*Tests.dll</td>
                        <td>include</td>
                        <td>NAnt test assemblies</td>
                    </tr>
                    <tr>
                        <td>extensions/common/neutral/**/*.dll</td>
                        <td>include</td>
                        <td>Framework and version-neutral assemblies</td>
                    </tr>
                    <tr>
                        <td>NAnt.MSNetTasks.dll</td>
                        <td>exclude</td>
                        <td>Microsoft.NET specific assembly</td>
                    </tr>
                    <tr>
                        <td>NAnt.MSNet.Tests.dll</td>
                        <td>exclude</td>
                        <td>Microsoft.NET specific test assembly</td>
                    </tr>
                </table>
            </div>
        </div>
        <div style="margin-left: 20px;">
            <p>
            <b>Unix</b>
            </p>
            <div style="margin-left: 20px;">
                <table style="width: 800px;" cellspacing="1" cellpadding="4">
                    <colgroup>
                        <col style="text-align: center;" />
                        <col style="text-align: center;" />
                        <col style="text-align: left;" />
                    </colgroup>
                    <tr>
                        <th>Pattern</th>
                        <th>Action</th>
                        <th style="text-align: left;">Description</th>
                    </tr>
                    <tr>
                        <td colspan="3"><hr /></td>
                    </tr>
                    <tr>
                        <td>*Tasks.dll</td>
                        <td>include</td>
                        <td>NAnt Core assemblies</td>
                    </tr>
                    <tr>
                        <td>*Tests.dll</td>
                        <td>include</td>
                        <td>NAnt test assemblies</td>
                    </tr>
                    <tr>
                        <td>extensions/common/neutral/**/*.dll</td>
                        <td>include</td>
                        <td>Framework and version-neutral assemblies</td>
                    </tr>
                    <tr>
                        <td>NAnt.MSNetTasks.dll</td>
                        <td>exclude</td>
                        <td>Microsoft.NET specific assembly</td>
                    </tr>
                    <tr>
                        <td>NAnt.MSNet.Tests.dll</td>
                        <td>exclude</td>
                        <td>Microsoft.NET specific test assembly</td>
                    </tr>
                    <tr>
                        <td>NAnt.Win32Tasks.dll</td>
                        <td>exclude</td>
                        <td>Win32 specific assembly</td>
                    </tr>
                    <tr>
                        <td>NAnt.Win32.Tests.dll</td>
                        <td>exclude</td>
                        <td>Win32 specific test assembly</td>
                    </tr>
                </table>
            </div>
        </div>
        <p>
            <b>NOTE</b>: all patterns are matched relative to the NAnt base directory, which is the directory in which NAnt.exe is located.
        </p>
        <h4><a id="automatic-runtime" />2.1.2 Runtime framework</h4>
        <p>
            Depending on the runtime framework on which NAnt is running, some additional directories are scanned.
        </p>
        <p>
            In general, the following include patterns are applied:
        </p>
        <div style="margin-left: 20px;">
            extensions/common/&lt;CLR version&gt;/**/*.dll<br/>
            extensions/&lt;framework family&gt;/neutral/**/*.dll<br/>
            extensions/&lt;framework family&gt;/&lt;framework version&gt;/**/*.dll<br/>
        </div>
        <p>
            <b>Example:</b>
        </p>
        <p>
            When running NAnt on Microsoft .NET Framework 1.0, assemblies matching the following pattern would be scanned:
        </p>
        <div style="margin-left: 20px;">
            extensions/common/1.0/**/*.dll<br />
            extensions/net/neutral/**/*.dll<br />
            extensions/net/1.0/**/*.dll
        </div>
        <p>
            <b>NOTE:</b> the exact set of patterns that are used for a given runtime framework is defined in the NAnt configuration file (NAnt.exe.config).
        </p>
        <h4><a id="automatic-project">2.1.3 Project</a></h4>
        <p>
            Whenever a build project is started, NAnt will scan the following directories for assemblies that match the *.dll pattern:
        </p>
        <ul>
            <li>
                &lt;Project Base Directory&gt;/extensions/common/neutral/
            </li>
            <li>
                &lt;Project Base Directory&gt;/extensions/common/&lt;CLR version&gt;/
            </li>
            <li>
                &lt;Project Base Directory&gt;/extensions/&lt;framework family&gt;/neutral/
            </li>
            <li>
                &lt;Project Base Directory&gt;/tasks/&lt;framework family&gt;/&lt;framework version&gt;/
            </li>
        </ul>
        <p>
            <b>Example:</b>
        </p>
        <p>
            For a project file located in &quot;c:\projects\log4net&quot; with NAnt running on the Microsoft .NET 2.0 runtime, NAnt would end-up scanning the following project-level directories:
        </p>
        <ul>
            <li>
                c:\projects\log4net\extensions\common\neutral\
            </li>
            <li>
                c:\projects\log4net\extensions\common\2.0\
            </li>
            <li>
                c:\projects\log4net\extensions\net\neutral\
            </li>
            <li>
                c:\projects\log4net\extensions\net\2.0\
            </li>
        </ul>
        <h3><a id="taskloader-forced" />2.2 Forced scan</h3>
        <p>
            To explicitly instruct NAnt to scan a certain assembly (or set of assemblies) for extensions, build authors can use the <a href="../tasks/loadtasks.html"><code>&lt;loadtasks&gt;</code></a> tasks.
        </p>
    </body>
</html>
